<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
 <head>
  <title>SimpleDBM Coding and Design Principles</title>
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
 </head>
 <body>
  <h1>SimpleDBM Coding and Design Principles</h1>
  <h2>Modular design</h2>
  <p>SimpleDBM is broken down into distinct modules. Each module implements a particular
  sub-system, and is contained in its own package. All module packages are located under 
  the org.simpledbm namespace. Example, org.simpledbm.locking.</p>
  <p>Each modules has a public API, which is specified via a set of Java interfaces.
  Classes must not be used as part of the public API, though there are a few exceptions.</p>
  <p>The module implementation is always contained in a package named 
  org.simpledbm.{module}.impl. Example, org.simpledbm.locking.impl.</p>
  <p>To make the modules reusable and as independent of each other as possible,
  the interface of a module is deliberately specified in general terms. Where
  possible, the direct dependence between modules is avoided. If two modules are
  dependent, then the only permissible way for one module to interact with another
  is to go via the public API. Modules are not allowed to depend upon implementation
  specifics of other modules.</p>
  <h2>Documentation</h2>
  <p>Most of the documentation for SimpleDBM is incorporated as Javadoc comments
  within the source code, and in package and overview documents. The aim is to keep the
  documentation as close to the source code as possible.</p>
  <p>Being an educational project, producing good documentation is high priority.</p>
  <h2>Java coding standards</h2>
  <p>Heavy use is made of the new <a href="http://java.sun.com/j2se/1.5.0/docs/guide/concurrency/index.html">concurrency packages</a> in Java 5.0. Enums are used 
  where appropriate. SimpleDBM does not define any Generic classes itself, but makes
  liberal use of Java 5.0 Generic classes.</p>
  <p>Fine grained thread locking is used to maximise concurrency. Using 
  coarse grained locking would have simplified the code, but would not have provided
  an opportunity for exploring various techniques for fine-grained locking. Deadlock is
  avoided by careful ordering of locks.</p>
  <p>Memory manangement is left to the Garbage Collector. Rather than using Object
  pools, SimpleDBM encourages the use of short-lived objects, on the basis that this aids the
  <a href="http://java.sun.com/docs/hotspot/gc5.0/gc_tuning_5.html">garbage collector</a> in reclaiming space more quickly. The aim is to keep permanently 
  occupied memory to a low level.</p>
  <p>Only checked Exceptions are used. Each module defines its own Exception hierarchy.
  Exceptions are always handled or passed up the stack - if they are ignored
  then this is documented in the code. Care is taken to report Exceptions properly.
  All error messages are given error codes.</p>
  <p>Particular attention is paid to cleaning up of resources. To ensure that resources are
  cleaned up during normal as well as exceptional circumstances, finally blocks are
  used.</p>
  <p>Debug messages are used liberally - and are executed conditionally so that if
  debug is switched off, there is minimal impact on performance.</p>
  <h2>Third party libraries</h2>
  <p>To void license compatibility issues, and to reduce dependency on third-party
  libraries, SimpleDBM makes little or no use of any external libraries. A custom 
  wrapper is used for logging, which uses the Java logging API underneath.</p>
  <h2>Test Cases</h2>
  <p>Each module is accompanied with JUnit test cases.</p>
  <h2>Release schedule</h2>
  <p>The system is designed so that each module is usable once it is delivered.
  This means that although the full system has not yet been constructed, the individual
  modules can be used as soon as they are available. See the <a href="status.html">Status</a>
  page for information about availability of modules.</p>
  <hr />
  <p>Copyright &#169; 2005 by 
  <a href="mailto:dibyendu@mazumdar.demon.co.uk">Dibyendu Majumdar</a>.</p>
 </body>
</html>